CKM_UNWRAP_TR31

This section provides a summary of CKM_UNWRAP_TR31.

Supported operations

FIPS Mode support

Key size range (bytes) and parameters

Parameter

None

Mechanism description

The CKM_UNWRAP_TR31 mechanism is used to import a new key to a token where the wrapped key format is described by ASC X9 TR 31-2018: Interoperable Secure Key Exchange Key Block Specification (Date Registered: April 15, 2018) and X9.143-2021. The base key, also known as the key block protection key (KBPK), must be a symmetric key of type CKK_DES2, CKK_DES3, or CKK_AES and match the algorithm implied by the Key Block Version ID. The KBPK must contain a CKA_MECHANISM_LIST attribute with CKM_UNWRAP_TR31 specified.

CKM_UNWRAP_TR31 contributes the following attributes to the new key object based on the content of the TR-31 header:

CKA_CLASS

CKO_SECRET_KEY if Algorithm = A, D, H, T

CKO_PRIVATE_KEY or CKO_PUBLIC_KEY if Algorithm = E, R, S

Note

Key blocks which contain asymmetric key types (RSA, DSA, or ECDSA) normally hold key pairs and therefore may unwrap to a CKO_PUBLIC_KEY or CKO_PRIVATE_KEY object. By default the CKO_PRIVATE_KEY class object is created, but the caller can specify that a CKO_PUBLIC_KEY object be created by setting the CKA_CLASS attribute in the new objects template.

CKA_KEY_TYPE

CKK_AES if Algorithm = A

CKK_DES if Algorithm = D

CKK_ECDSA if Algorithm = E

CKK_GENERIC_SECRET if Algorithm = H

CKK_RSA if Algorithm = R

CKK_DSA if Algorithm = S

CKK_DES2 or CKK_DES3 if Algorithm = T (depending on key size recovered)

Usage attributes may be specified in the user template but must match the allowed attributes listed in the table below or be equal to False; that is, you cannot set an attribute to True unless it is allowed in the key block header.

Cryptoki usage attributes are allowed based on the TR-31 header Key Usage and Mode of Use fields, as shown in the following list:

B3

Definition

Key derivation key (non-ANSI X9.24)

Allowed attribute

CKA_DERIVE = True if Mode = X

Note

If the 'DA' optional block is present then the CKA_DERIVE will be forced False.

D0

Definition

Symmetric data encryption

Allowed attribute

CKA_ENCRYPT = True if Mode = B or E

CKA_DECRYPT = True if Mode = B or D

D1

Definition

Asymmetric data encryption

Allowed attribute

CKA_ENCRYPT = True if Mode = B or E

CKA_DECRYPT = True if Mode = B or D

K0

Definition

Key encryption or wrapping

Allowed attribute

CKA_WRAP = True if Mode = B or E

CKA_UNWRAP = True if Mode = B or D

K1

Definition

TR-31 key block protection key

Allowed attribute

CKA_WRAP = True if Mode = B or E

CKA_UNWRAP = True if Mode = B or D

CKA_MECHANISM_LIST = CKM_WRAP_TR31_DERIVE + CKM_WRAP_TR31_VARIANT and/or CKM_UNWRAP_TR31 + CKM_UNWRAP_TR31_DISCARD

K2

Definition

Asymmetric key pair (KRD) ANSI X9.139/TR-34

Allowed attribute

CKA_ENCRYPT = True if Mode = B or E

CKA_DECRYPT = True if Mode = B or D

K3

Definition

Asymmetric key for key agreement/key wrapping

Allowed attribute

CKA_WRAP = True if Mode = B or E

CKA_UNWRAP = True if Mode = B or D

CKA_DERIVE = True if Mode = X

K4

Definition

Key block protection key, ISO 20038

Allowed attribute

CKA_WRAP = True if Mode = B or E

CKA_UNWRAP = True if Mode = B or D

CKA_MECHANISM_LIST = CKM_WRAP_TR31_DERIVE + CKM_WRAP_TR31_VARIANT and/or CKM_UNWRAP_TR31 + CKM_UNWRAP_TR31_DISCARD

M0, M1, M2, M3, M4, M5, M6, M7, M8

Definitions

ISO 16609 MAC algorithm 1 (using TDEA)

ISO 9797-1 MAC algorithm 1

ISO 9797-1 MAC algorithm 2

ISO 9797-1 MAC algorithm 3

ISO 9797-1 MAC algorithm 4

ISO 9797-1999 MAC algorithm 5

ISO 9797-1:2011 MAC Algorithm 5/CMAC HMAC

ISO 9797-1:2011 MAC Algorithm 6

Allowed attributes

CKA_SIGN = True if Mode = C or G

CKA_VERIFY = True if Mode = C or V

Note

If an HMAC key is specified and a 'HM' (HMAC mechanism) optional block is included, then a CKA_MECHANISM_LIST attribute with two mechanisms is added by the HSM based on the HM value. See the table below for the list of mechanism pairs.

S0

Definition

Asymmetric key pair for digital signature

Allowed attribute

CKA_SIGN and CKA_SIGN_RECOVER = True if Mode = S

CKA_VERIFY and CKA_VERIFY_RECOVER = True if Mode = V

S1

Definition

Asymmetric key pair, CA key

Allowed attribute

CKA_SIGN = True if Mode = S

CKA_VERIFY = True if Mode = V

S2

Definition

Asymmetric key pair (non-X9.42)

Allowed attribute

CKA_SIGN and CKA_SIGN_RECOVER = True if Mode = S or T

CKA_VERIFY and CKA_VERIFY_RECOVER = True if Mode = V

CKA_DECRYPT = True if Mode = T or D or B

CKA_ENCRYPT = True if Mode = E or B

CKA_WRAP = True if Mode = E or B

CKA_UNWRAP = True if Mode = D or B

The table below lists the mechanism pairs added by the HSM if an HMAC key and 'HM' optional block are included. Mechanism pairs are listed by HM value. If the HM value is not recognized, CKR_MECHANISM_PARAM_INVALID is returned. Mechanisms may be recognized but not supported.

The following mechanisms are not supported by the HSM

The following attributes will have the specified default values but may be overridden by the attribute template supplied to the mechanism:

¹ Cannot be set False if the No Clear PINs security flag is set.

² Cannot be set True

CKA_MECHANISM_LIST can only be specified in the template if the mechanism does not also want to contribute this attribute; that is, the user cannot override the default attribute shown in the table above.

CKA_EXTRACTABLE is defaulted as specified by the header Exportability byte but may be forced False by the caller.

CKA_LOCAL, CKA_ALWAYS_SENSITIVE, and CKA_NEVER_EXTRACTABLE will be set False.

Key block optional blocks that are not otherwise mentioned in this specification are ignored by the HSM.

Return to ProtectToolkit-C mechanisms.